﻿#region Copyright & License
//
// Project: Quark Framework
// Project site: http://quark.codeplex.com
// See the copyright statement on the project site for more details.
//
// Licensed to the Apache Software Foundation (ASF) under one or more 
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership. 
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with 
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Quark.Framework.Exceptions;

namespace Quark.Framework.Container
{
    /// <summary>
    /// 组件实例选择器接口，用于向<see cref="IComponentInstanceCollection"/>提供选择实例的策略
    /// </summary>
    public interface IComponentInstanceSelector
    {
        /// <summary>
        /// 从当前实例集合中返回一个组件实例，
        /// 等同于参数constraints传入null的<see cref="IComponentInstanceSelector.GetComponentInstance(object)"/>方法调用
        /// </summary>
        /// <returns>返回组件实例</returns>
        /// <exception cref="NoValidComponentInstanceExistsException">没有可用的组件实例并且创建组件新实例失败，内部抛出的异常统一以<see cref="NoValidComponentInstanceExistsException"/>作为异常封装</exception>
        /// <threadsafety/>
        IQuarkComponent GetComponentInstance();

        /// <summary>
        /// 从当前实例集合中返回一个组件实例
        /// </summary>
        /// <param name="constraints">查找条件参数，传入null空值表示没有查找条件的限制</param>
        /// <returns>返回组件实例</returns>
        /// <exception cref="NoValidComponentInstanceExistsException">没有可用的组件实例并且创建组件新实例失败，内部抛出的异常统一以<see cref="NoValidComponentInstanceExistsException"/>作为异常封装</exception>
        /// <threadsafety/>
        IQuarkComponent GetComponentInstance(object constraints);

        /// <summary>
        /// 从当前实例集合中返回一个类型化的组件实例，
        /// 等同于参数constraints传入null的<see cref="IComponentInstanceSelector.GetComponentInstance{T}(object)"/>方法调用
        /// </summary>
        /// <typeparam name="TComponent">组件实例类型，可以是组件的接口类型</typeparam>
        /// <returns>返回组件实例</returns>
        /// <exception cref="NoValidComponentInstanceExistsException">没有可用的组件实例并且创建组件新实例失败，内部抛出的异常统一以<see cref="NoValidComponentInstanceExistsException"/>作为异常封装</exception>
        /// <threadsafety/>
        TComponent GetComponentInstance<TComponent>() where TComponent : class;

        /// <summary>
        /// 从当前实例集合中返回一个类型化的组件实例，
        /// 等同于对返回结果做类型转换的<see cref="IComponentInstanceSelector.GetComponentInstance(object)"/>方法调用
        /// </summary>
        /// <typeparam name="TComponent">组件实例类型，可以是组件的接口类型</typeparam>
        /// <param name="constraints">查找条件参数，传入null空值表示没有查找条件的限制</param>
        /// <returns>返回组件实例</returns>
        /// <exception cref="NoValidComponentInstanceExistsException">没有可用的组件实例并且创建组件新实例失败，内部抛出的异常统一以<see cref="NoValidComponentInstanceExistsException"/>作为异常封装</exception>
        /// <threadsafety/>
        TComponent GetComponentInstance<TComponent>(object constraints) where TComponent : class;
    }
}
